Creating Variable Functions

This document describes how to create variable functions. Also see:

Class Inheritance

You can create your own functions for any IDL data type (except structures and objects). The variable classes have the following inheritance structure:

 

 

You can create new functions on any of the IDL Data Type classes (such as IDL_Byte) or any of the superclasses (IDL_Integer, IDL_Number, and IDL_Variable).

When you create a new function and add it to IDL's path, that function will immediately become available to all variables of that data type within your IDL session. In addition, if your function is on one of the superclasses, then the function will become available to all subclasses. For example:

Note: All variable methods must be functions, not procedures.

Arguments and Keywords

Your variable function should have the following signature:

function Class::MyFunction, variable [, arg2, arg3, ...] [KEYWORD=keyword, ...]

compile_opt IDL2, STATIC

...

return, result

end

The first argument is always set equal to the variable that was used to invoke the function. You can have any number of other arguments and keywords.

Be sure to use "compile_opt STATIC" to mark your function as a static method.

Example: IDL_Variable Function

We will create a function called IDL_Variable::Serialize that will convert any IDL variable (except structures and objects) to a JSON string and optionally save the string to a file. Create the following code and save it to a file called "idl_variable__serialize.pro":

function IDL_Variable::Serialize, variable, FILE=file

; Use STATIC to mark this as a static method

compile_opt IDL2, STATIC

ON_ERROR, 2

; Convert the variable to a JSON string.

; If type is a pointer, then dereference.

result = JSON_SERIALIZE((variable.tname eq 'POINTER') ? $

*variable : variable)

; Optionally save the JSON to a file.

if (ISA(file)) then begin

OPENW, lun, file, /GET_LUN

PRINTF, lun, result

FREE_LUN, lun

endif

return, result

end

For example:

IDL> data = FINDGEN(3,2)

IDL> HELP, data.Serialize()

IDL> PRINT, data.Serialize()

[[0.0,1.0,2.0],[3.0,4.0,5.0]]

IDL prints:

<Expression> STRING = '[[0.0,1.0,2.0],[3.0,4.0,5.0]]'

[[0.0,1.0,2.0],[3.0,4.0,5.0]]

Using the same function with a string array for input:

IDL> arr = ['abc', 'def', 'ghi', 'idl']

IDL> void = arr.Serialize(FILE='mydata.json')

Example: IDL_String Function

Now we will create a function that will take a JSON string and convert it back to an IDL variable. Create the following code and save it to a file called "idl_string__parsejson.pro":

function IDL_String::ParseJSON, json

; Use STATIC to mark this as a static method

compile_opt IDL2, STATIC

ON_ERROR, 2

result = JSON_PARSE(json, /TOARRAY, /TOSTRUCT)

return, result

end

Here, we take a valid JSON string and call the function:

IDL> json = '{"key1":0.0, "key2":[1,2,3], "key3":true}'

IDL> result = json.ParseJSON()

IDL> help, result

IDL prints:

** Structure <107234a0>, 3 tags, length=40, data length=33, refs=1:

KEY1 DOUBLE 0.00000000

KEY2 LONG64 Array[3]

KEY3 BOOLEAN true (1)

See Also